******************************************************************* * * * (C) Copyright International Business Machines Corporation 1993. * * All rights Reserved. * * * ******************************************************************* ALPHA V2.3 Lionel de Lambert - Iunius MMDCCXLIII AUC IBM United Kingdom Laboratories Ltd. 16 January 1995 This document describes the installation, function and commands of the ALPHA software analysis programme which runs under the OS/2 v2.x operating system. The languages supported are :- 370 and 386 assembler, PASCAL(Ada), PL/X(PL/I, REXX), C(C++), and FORTRAN. Description =========== This is a simple 32-bit configurable multi-document highlighting editor version of the alpha software analysis programmes which were written together with the CMS programme ANALYSE in order to establish the praecognita for the CICS restructure project and may be of interest to those people who examine 370, 386 assembler, PASCAL(Ada), PL/X(PL/I, REXX), C(C++), FORTRAN etc. under OS/2 V2.x. This programme will provide basic browse and edit functions for all files with a record size <=256 as well as highlighting specified keywords for language files such as 370 & 386 Assemble, PASCAL, PL/AS, C(CPP), FORTRAN etc. ALPHA will also display the programme call structure, and expand the procedure calls in a secondary window. This version of Alpha was written in C-Set/2 and MASM V6.0 and will run on OS/2 V2.0 or later. Highlighting of keywords has been provided for the following language types :- A37,ASM,PAS,(PLS,PLX,PLI),(C,CPP,H),FOR,IPF The syntax of the Alpha programme is :- START ALPHA [file] [/p [profile name - default ALPHA.PRF]] The Language_colour, Language_operator, Precedent_C, File_type, Comment_start, Comment_end, Transfer_pgm(1) and Window keywords are the only ones which are recognized from the profile. {The main window position is remembered when Alpha is closed.} Installation ============ The minimum requirement is to copy the file ALPHA.EXE to a directory under OS/2 v2.x. If you want to access the Extended help you must copy the file ALPHA.HLP in to the HELP path. If you wish to use the Alpha fonts you should copy the ALPHA.FON file to a directory under OS/2 v2.x and select 'System Setup' from 'OS/2 System' and use 'Add' in the 'Edit font' of the 'Font Palette'. If you wish to access files from the host then you should also install a file transfer programme such as ALMCOPY. Menu ==== The Allocate dialogue box is used to request a file to be read. If the drive letter is changed then the OK button should be used to refresh the List boxes. A file may also be allocated by dragging mouse button 2 with the Ctrl key pressed from a Drives window and releasing it over the Alpha window. {The maximum number of child windows is 16.} The Profile button may be used to remember the file name entered in the Combo box as the profile for subsequent invocations. This will obviate the need for the '/p' option and allow the dropping of files on the unstarted programme. A null file name will remove the saved profile name. The Transfer button will pass the contents of the Combo box to the Transfer_pgm. The Command dialogue box(2) may be used to issue a search command e.g. Non-case sensitive search for a string. Case sensitive search for a string. Case sensitive search for a string in column one. (The string search starts from the current cursor position +1.) Move to a specified line number. Replace the text at the current cursor position with the text from the Replacement Text Entry Box. Options ======= The Options menue may be used to set the following options :- Statement No. - display the statement number in the TITLE bar. Tab - expand the record by using X'09' characters to round to columns n*8. Keyword - highlight the keywords. Include - For the file types of MASM, PASCAL, PL/S {PL/I etc.} and C read the include files specified by :- include file_name, {$INCLUDE : 'file_name' }, %INCLUDE first_part_of_file_name;, #include , respectively when expanding a call etc. {The current directory together with the paths defined by the INCLUDE environment variable will be searched. The total number of open files/windows is limited to 16 so the include nesting level can not exceed 16 - the number of open windows. For language 4, PL/S, the file extension is appended to the first_part_of_file_name.} Grid - Draw vertical grid lines through every tenth character in the Grid colour. Box - Switch the select mode to box format. In box mode the "Paste" function will overwrite the text at the cursor position with the box area. Tool bar - Display the "Tool bar"; which makes toggling of some options easy. Configure ========= This will invoke the Configure notebook with the following pages :- C - Colour - Set the text colour F - Font - set the text font. T - Configure the Tool bar. Font ---- The Font dialogue box may be used to change and remember the font of the text, comments etc. You can use the System Monospaced, Helvetica, Roman and Courier fonts but the Courier, System VIO and the System Monospaced fonts are the only monospaced fonts supplied with OS/2 V2.x. A monospaced font with point sizes 8,9,10,11,16 & 20 is supplied with the ALPHA PACKAGE, which may also be used. Outline fonts are not selectable. Point sizes (1/72") are :- Courier (8,10,12), Roman (8,10,12,14,18,24), Helvetica (8,10,12,14,18,24), System (8,10,12, {8x8, 8x16,9x20}), "Alpha" (8{8x12},9{9x10},10{8x14},11{11x12},16{12x16},20{12x20}). The Alpha font point size 10 is suitable for 8513 screens and the point size 20 for 8515/8516. Colour ------ The Colour dialogue box may be used to change and remember the colours(3) of the text, comments etc. The following colours may be changed with this dialog box :- Text - The main text colour. Highlight - The mouse button 1 isolate keyword. Locate/Position - The mouse button 2 locate string, the character position of the last mouse button 1 click and the Structure List box procedures. Comment/statement# - The Comment colour, statement number and Structure List box calls. Background - The text background colour. Branch - The Branch/Jump instruction colour. Grid/Help balloon - The vertical grid line colour and the Tool bar help balloon background. Select area - The mouse button 1 drag area. Help balloon - The Tool bar help balloon colour. Comment background - The background colour for the comment text. Configure Tool bar ------------------ This Dialog box may be used to Delete or Add buttons to the Tool bar and to change its size and orientation. - The Buttons List box contains the available buttons; one should be selected and the Add button pressed to add it to the Tool bar. - The Tool bar List box shows the current list of buttons in the Tool bar; one should be selected and the Delete button pressed to remove it. - The Entry box displays the current button size which may be changed. - The Horizontal and vertical Radio buttons will read the Entry box and reconstruct the Tool bar. - The menu Radio button will cause the Tool bar to be placed in the menu when Alpha is restarted. - The Configure button will cause the changes to be applied. The new Tool bar structure will be remembered when Alpha is closed. If the Tool bar is changed from menu to floating then Alpha should be closed and restarted. The Print dialogue box may be used to print a range of records on one of :- LPT1, LPT2, LPT3. If a range of records has been selected by dragging the mouse with button one down then this range will be used in the print dialogue box. The default record range is the whole file. The Window menu may be used to close all child windows or to arrange them so that the title text is visible, Cascade, or so that a partial view of each child may be seen, Tile. The Select window option will create a dialogue box from which a child window may be selected to become the active widow. The first six windows may be selected by file name from this menu. The Edit dialogue box may be used to edit the current line :- - The Multi-Line Entry box may be used to modify the current line or add new lines. The number of lines added is the No. of lines in the MLE. - The Modify button will replace the current line with the contents of the MLE. - The Undo button will undo the changes to the MLE. - The Cancel button will leave the current line unchanged. - The number on the left shows the current cursor position in the MLE. - The number on the right shows the current pointer, mouse, position in the MLE. The current line is the top line in the window unless button 1 has been pressed when the cursor will indicate the line. If major modifications, {The Multi-line Entry field will only accept 64 lines at a time}, are to be made to the file then a purpose built editor should be used. The maximum record size allowed is 256. Help ---- The Help menu may be used to display the About window, the Help summary window or access the OS/2 help file ALPHA.HLP(5). The Help summary window may be scrolled by :- Page_up - scroll up 1 screen Page_down - scroll down 1 screen Home - scroll to the top of the Help data End - scroll to the end of the Help data Up_arrow - scroll up 1 line. Down_arrow - scroll down 1 line. The mouse button 1 will highlight a string and mouse button 2 will cause a case sensitive search for this string from the current cursor position +1, {if the Ctrl key is held down then the search is not case sensitive}. If the Ctrl key is held down when the mouse button 1 is pressed then the current line may be edited. If mouse button 1 is clicked twice on a label then a search from the top of the file is made for the label definition or procedure entry and a secondary window is opened, Expand. {The language structure tables are searched first so if you have specified some structure keywords via. Language_operator then you will have to record the structure first, Ctrl+s.} If mouse button 1 is clicked twice on BEGIN for PASCAL, { for C or DO for PL/S then the following records up to the matching END etc. will not be displayed. If the mouse button 1 is double clicked on the suppressed message line or F12 is pressed then the records will be re-displayed. If the Include option is effective and mouse button 1 is double clicked on an Include statement then a second window containing the include file will be created. The following keys are effective for the programme - F1 will open the Help window. F2 will open the Configure Notebook. F3 will close the programme. F4 will open the Allocate file dialogue box. F5 will repeat the previous command. F6 will open the Command dialogue box. F7 will scroll the window up 1/2 a screen. F8 will scroll the window down 1/2 a screen. F12 will reset the collapse of the BEGIN/END pairs etc. Page_Up will scroll up 1 screen. Page_Down will scroll down 1 screen. The Home key will scroll to the top of the file. The End key will scroll to the end of the file. Up_arrow - scroll up 1 line. Down_arrow - scroll down 1 line. Left_arrow - scroll left 1 column. Right_arrow - scroll right 1 column. (Hold down the Shift key to highlight an area of the window.) The Insert key will toggle the Insert/Overwrite mode for character Edit in the Child window at the current cursor position. The Insert+Shift keys will insert the lines from the Clipboard at the current cursor position. The Insert+Ctrl keys will copy the lines highlighted by the button(4) 1 drag area from the display to the Clipboard. The Delete key will delete the character or select area at the current cursor position in the child window. The Delete+Shift keys will copy the selected area to the Clipboard and delete the text. The Space+Ctrl keys will clear the selected area to blanks. The Ctrl+b keys will re-insert the last deleted records. The Ctrl+e keys will edit the current line. The current line will be the top line in the window unless button 1 has been pressed when the cursor will indicate the the line. The Ctrl+h will hide/restore the selected lines. The Ctrl+shift+s keys will save the current file. The Ctrl+s keys will record or display the programme structure. {The programme calling structure will be recorded if this has not already been done and then the Structure dialog box will be displayed. If an entry from the List box is selected then the last active window will be scrolled to that line. The Print button may be used to print the contents of the List box on LPT1. The calling structure is based on the profile keywords :- Language_operator, Precedent_C and File_type. If the file contains tab characters then Tab expansion must be active before the structure is recorded.} The Ctrl+x keys will display the record references to the highlighted label. The Ctrl+c keys will suppress/display the comments in a language file. If a single line is scrolled then the comment suppression will be disabled. The Ctrl+Shift+c keys will compile the last active file using the command displayed in the Compile dialogue box which will be scanned and the % replaced by the file name from the file entry box. The resultant command will be executed when the Execute button is pressed. The Standard Output for the Child process will be written to the "Output" MLE. The programme name is formed by appending ".EXE" to the first name of the command line. If the command line is modified then it will be remembered when Alpha is closed. The Alt+n keys will record a bookmark, where n is a numeric key 0-9. The Ctrl+n keys will move to the bookmark. Profile ======= A profile(6) may be specified defining the following keyword values, these are the only ones recognized by the Alpha programme:- File_type specifies the File types to be recognized. The string must be <=64 characters and terminated by a comma. The first 6 types are used for :- 370 assembler 386 assembler PASCAL, (Ada) PL/S, PL/AS, PL/I etc., (REXX) C(C++) FORTRAN For REXX files use :- "A37,ASM,PAS,CMD,C,FOR," and replace the PL/S entries in the Language_colour entries. For Ada files use :- "A37,ASM,ADA,PLS,C,FOR," and replace the PAS entries in the Language_colour entries. If a file extension is an alias then place the extensions in parenthesis, e.g. "A37,ASM,PAS,PLS,(C,CPP),FOR,". Comment_start specifies the first two characters of the start of a comment. The string must be œ12 characters. The 6 pairs are used for :- 370 assembler 386 assembler PASCAL, for Ada specify Comment_start="* ; --/*/*C " PL/S, PL/AS etc. C FORTRAN The default value is Comment_start="* ; { /*/*C ". If the second character of the pair is a blank then the comment is assumed to begin with a single character. Comment_end specifies the last two characters of the comment. The string must be œ12 characters. The 6 pairs are used as in Comment_start. The default value is Comment_end=" } */*/ ". If the second character of the pair is a blank then the comment is assumed to terminate with a single character. Precedent_C specifies the C language keywords which precede a procedure, e.g. int, char, etc. The string must be <=64 characters and terminated by a comma. Language_colour defines the highlight colours for key words. Up to 255 entries may be defined as follows :- file_type,key_word,colour,scan_length and are terminated by .END, invalid entries are ignored. The colour may be a single colour or an expression viz. :- (,,) The case and spaces within the keyword are significant, {the first character is used for the initial scan so a space would reduce the performance}. The keywords must be <=12 characters. {Colours may take the values :BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN, BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE (ORANGE, PURPLE, PALEGREEN, PALEBLUE)} Language_operator defines the operator keywords for each language. The second value indicates how to process the keyword, viz. < or > indicate the scan direction from the keyword to locate the label, 'P' or 'C' indicates that the keyword specifies an entry point or call, ':' indicates that the label will be followed by a colon, '2' indicates that the second label following a ',' is to be used. Up to 32 entries may be defined as follows :- file_type,<º>CºP[:][2],keyword and are terminated by '.END', invalid entries are ignored. The keywords must be <=12 characters. The C-language procedure values are supplied on the Precedent_C keyword. Window specifies the initial window position. A suitable value for 8515 and 8516 type screens may be - (0,60,800,600). If no profile is specified then Window=(0,60,420,635) is assumed. When the main window is closed its position will be remembered. Transfer_pgm specifies the programme name invoked from the Allocate widow. The data from the COMBO box is passed without modification to the Transfer_pgm when the Transfer button is selected. Tool bar ======== The Tool bar may be used to set an option etc. quickly. The Tool bar position and state will be remembered when the Alpha programme is closed. The following buttons are available :- - Hide/re-instate highlighted records from display. - Display/Create structure List box. - Toggle statement No. display. - Copy highlighted records to Clipboard. - Cascade Child windows. - Tile Child windows. - Toggle Tab expansion. - Toggle Include option. - Repeat last Locate command. - display the record references to the highlighted label. - suppress/display the comments in a language file. If a single line is scrolled then the comment suppression will be disabled. - Edit the current line. - Save the file. - Compile file - Copy the selected records to the Clipboard and erase from from memory. - Overwrite the current line with records from the Clipboard. - Delete records from memory. - Re-insert the last deleted records. - Clear select area. - Switch to/from box mode select. If mouse button 2 is held down on a button then a small help balloon will be displayed. Add/Modify a language ===================== Alpha has within it (hard coded) routines which understand certain language features e.g. 370 Assembler labels start in start in column 1, procedures are invoked by BAL, BAS etc. and PASCAL procedures are preceded by FUNCTION or PROCEDURE(7) etc.. There are 6 such languages 'understood' by Alpha, viz. :- 370 Assembler 386 Assembler PASCAL (Ada) PL/AS (PL/I, REXX) C FORTRAN Because Ada is similar to PASCAL and PL/I & REXX are similar to PL/AS, in respect to procedure calls etc., you can also analyse these languages by pretending they are type 3 & 4 respectively. However, you can interpret any language/file type (use the highlighting facility) by supplying extra definitions in a profile which is specified as a parameter to Alpha e.g. START ALPHA /p profile_name A sample profile (ALPHA.PRF) is provided in the package, which includes comments explaining the use of the keywords. This may be edited to change/add a file extension by modifying the following keywords :- File_type - list of file extensions up to 64 characters Comment_start - list of comment start character pairs (blank is ignored) up to 12 characters. Comment_end - list of comment end character pairs (blank is ignored) up to 12 characters. Precedent_C - list of procedure keywords for language 5 which precede a procedure definition, up to 64 characters. Language_colour - list of keyword definitions file_type,keyword,colour,maximum scan length Language_operator - list of language operator values and attributes file_type,atributes,keyword e.g. to add language XYZ with a routine call 'ICALL routine_name' with similar structure to PL/S the profile would include the following statements :- File_type="A37,ASM,PAS,XYZ,C,FOR," Language_colour XYZ,ICALL,DARKGREEN,72 XYZ,Next_key ,RED,72 .END Language_operator XYZ,>C,ICALL .END Only the first 6 language types will allow the Expand and Structure operations to be effective. This implies that you could not use all the features of Alpha for a new language which did not have the call/label syntax of one of the existing languages. The ALPHA programme scans the keyword table in the order specified in the profile, so a later entry may replace a former entry. Writing a parser exit DLL ========================= If the DLL, ALPHAE.DLL, has been provided in the LIBPATH then the procedure Alpha_parse_exit will be called from the WM_PAINT child window procedure. A sample source module ALPHAE.C is provided which may be used to create a DLL with a parser exit procedure. This module may be used to write the records to the child window. Changes to the ALPHA package since August 1994 =============================================== 1) Ctrl+h - Hide/restore selected records. 2) Parse exit from WM_PAINT procedure. 3) Delete - erase a single character or the selected area. 4) Tool bar in menu. 5) Language_colour may contain forground and background colours. 6) Ctrl + mouse button 2 will cause a non-case sensitive search. 7) Ctrl+b - will re-insert the last deleted records. 8) Option Box - set box mode select. 9) Space+Ctrl - clear select area. Notes ===== 1 The data in the Allocate COMBO will be passed without modification to the Transfer_pgm. 2 The COMBO box will hold the previous three search strings entered. 3 The colours may take the values :BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN, BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE, ORANGE, PURPLE, PALEGREEN, PALEBLUE, COLOUR1. {The last five colours will not be available on VGA screens. The COLOUR1 value may be set by the sliders and will be remembered when Alpha is closed.} 4 If mouse button 1 is held down and moved to the bottom or top of the window the window will continue to scroll untill the button is released or the mouse is moved back within the window. 5 The ALPHA2.HLP file must be installed in the HELP path. 6 A sample profile is supplied with the name ALPHA.PRF. This file may be edited to alter the programme defaults. The profile is read by specifying /p as a parameter to the programme. 7 These keywords and attributes may be specified by the Language_operator keyword in the profile. =============== End of Alpha text file =============================